/*!
 * \file ITrdNotifySink.h
 * \project	WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief UFT交易通知接口定义文件
 * 
 * \details 该文件定义了ITrdNotifySink交易通知回调接口，用于接收UFT交易过程中的各种事件通知：
 *          - 成交回报通知
 *          - 订单状态变化通知
 *          - 持仓变化通知
 *          - 交易通道状态通知
 *          - 委托确认通知
 *          这是UFT系统中的关键回调接口，确保交易事件能够及时准确地传递给上层应用
 */
#pragma once
#include <stdint.h>
#include "../Includes/WTSMarcos.h"

NS_WTP_BEGIN

/*!
 * \class ITrdNotifySink
 * \brief UFT交易通知回调接口
 * 
 * \details 该接口定义了UFT交易系统中各种事件的回调方法，包括：
 *          - 成交事件：当订单成交时触发
 *          - 订单事件：当订单状态发生变化时触发
 *          - 持仓事件：当持仓发生变化时触发（可选实现）
 *          - 通道事件：当交易通道连接/断开时触发
 *          - 委托事件：当委托提交后收到确认时触发（可选实现）
 * 
 * \note 该接口采用纯虚函数设计，必须由具体的交易策略或管理器实现
 *       所有回调方法都在交易线程中执行，需要注意线程安全
 */
class ITrdNotifySink
{
public:
	/*!
	 * \brief 成交回报回调
	 * \param localid 本地订单ID
	 * \param stdCode 标准合约代码
	 * \param isLong 是否多头方向（true=多头，false=空头）
	 * \param offset 开平标识（0=开仓，1=平仓，2=平今，3=平昨）
	 * \param vol 成交数量
	 * \param price 成交价格
	 * 
	 * \details 当订单部分成交或全部成交时触发该回调，提供详细的成交信息
	 *          策略可以根据成交信息更新内部状态、计算盈亏、调整仓位等
	 */
	virtual void on_trade(uint32_t localid, const char* stdCode, bool isLong, uint32_t offset, double vol, double price) = 0;

	/*!
	 * \brief 订单回报回调
	 * \param localid 本地订单ID
	 * \param stdCode 标准合约代码
	 * \param isLong 是否多头方向（true=多头，false=空头）
	 * \param offset 开平标识（0=开仓，1=平仓，2=平今，3=平昨）
	 * \param totalQty 委托总量
	 * \param leftQty 剩余未成交数量
	 * \param price 委托价格
	 * \param isCanceled 是否已撤销（默认为false）
	 * 
	 * \details 当订单状态发生变化时触发该回调，包括订单提交、部分成交、全部成交、撤销等状态
	 *          通过剩余数量可以判断订单的完成状态：leftQty=0表示全部成交，leftQty>0表示部分成交
	 */
	virtual void on_order(uint32_t localid, const char* stdCode, bool isLong, uint32_t offset, double totalQty, double leftQty, double price, bool isCanceled = false) = 0;

	/*!
	 * \brief 持仓变化回调（可选实现）
	 * \param stdCode 标准合约代码
	 * \param isLong 是否多头方向（true=多头，false=空头）
	 * \param prevol 变化前总持仓
	 * \param preavail 变化前可用持仓
	 * \param newvol 变化后总持仓
	 * \param newavail 变化后可用持仓
	 * \param tradingday 交易日期
	 * 
	 * \details 当持仓数量发生变化时触发该回调，提供持仓变化的详细信息
	 *          包括总持仓和可用持仓的变化前后对比
	 *          默认为空实现，策略可以选择性重写该方法
	 */
	virtual void on_position(const char* stdCode, bool isLong, double prevol, double preavail, double newvol, double newavail, uint32_t tradingday) {}

	/*!
	 * \brief 交易通道就绪回调
	 * 
	 * \details 当交易通道连接成功并准备接收交易指令时触发该回调
	 *          策略可以在该回调中执行初始化操作、查询持仓、启动交易逻辑等
	 */
	virtual void on_channel_ready() = 0;

	/*!
	 * \brief 交易通道断线回调
	 * 
	 * \details 当交易通道连接丢失时触发该回调
	 *          策略应在该回调中停止发送新的交易指令，保存状态，等待重连
	 */
	virtual void on_channel_lost() = 0;

	/*!
	 * \brief 委托回报回调（可选实现）
	 * \param localid 本地订单ID
	 * \param stdCode 标准合约代码
	 * \param bSuccess 委托是否成功
	 * \param message 回报消息（成功时通常为空，失败时包含错误信息）
	 * 
	 * \details 当委托提交后收到交易所确认时触发该回调
	 *          可以用于确认订单是否被交易所接受，以及获取拒绝原因
	 *          默认为空实现，策略可以选择性重写该方法
	 */
	virtual void on_entrust(uint32_t localid, const char* stdCode, bool bSuccess, const char* message){}
};

NS_WTP_END